github-markdown-adf 1.0.1 → 1.2.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/github-markdown-adf)](https://www.npmjs.com/package/github-markdown-adf)
 [![CI](https://github.com/joroden/github-markdown-adf/actions/workflows/ci.yml/badge.svg)](https://github.com/joroden/github-markdown-adf/actions)
+[![Socket Badge](https://badge.socket.dev/npm/package/github-markdown-adf)](https://badge.socket.dev/npm/package/github-markdown-adf)
 [![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](https://unlicense.org)
 
 Bidirectional **GitHub Flavored Markdown (GFM) to / from Atlassian Document Format (ADF)** converter. 
@@ -137,20 +138,39 @@ import { mdToAdf, adfToMd } from 'github-markdown-adf';
 
 ### `mdToAdf(markdown: string): AdfDoc`
 
-Converts a GFM string to an ADF document object. Parses using [remark](https://github.com/remarkjs/remark) / [unified](https://github.com/unifiedjs/unified) with full GFM extensions: tables, task lists, strikethrough, and GitHub Alert syntax (`> [!NOTE]`, `> [!WARNING]`, etc.).
+Converts a GFM string to an ADF document object. Parses using mdast and micromark GFM extensions, with support for tables, task lists, strikethrough, and GitHub Alert syntax (`> [!NOTE]`, `> [!WARNING]`, etc.).
 
-### `adfToMd(adf: AdfDoc): string`
+### `adfToMd(adf: AdfDoc, options?: AdfToMdOptions): string`
 
 Converts an ADF document object to a GFM string. Handles all standard ADF node and mark types and produces clean, readable output targeting GitHub Flavored Markdown.
 
+## Options
+
+`adfToMd` accepts an optional second argument to control rendering behaviour.
+
+### `AdfToMdOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `mentions` | `boolean` | `true` | When `true`, renders mention nodes as the display text if available, otherwise as `@{id}`. When `false`, renders as plain text: display text if available, otherwise just the bare `{id}` without an `@` prefix. |
+
+### Usage example
+
+```typescript
+// Render mentions as plain text instead of @-tagged references
+const md = adfToMd(adfDoc, { mentions: false });
+```
+
 ## TypeScript Types
 
-All ADF types are exported for use in your own code:
+All ADF types and option interfaces are exported for use in your own code:
 
 ```typescript
 import type { AdfDoc, AdfNode, AdfMark, AdfInlineNode, AdfTopLevelBlockNode } from 'github-markdown-adf';
 // Also available: ParagraphNode, HeadingNode, TableNode, PanelNode, CodeBlockNode,
 // BulletListNode, OrderedListNode, TaskListNode, TextNode, MentionNode, ...and more
+
+import type { AdfToMdOptions } from 'github-markdown-adf';
 ```
 
 ## Requirements